folders

Type

function

Summary

List the subfolders in a folder.

Syntax

the [{ detailed | long }] folders

folders([<targetFolder>[, <outputKind>]])

Description

Return a list of folders in the targetFolder, with one file per line. If no targetFolder is specified, list the files in the current folder.

The list only includes folders at the top level of the targetFolder. The folders function does not recursively enter and examine folders deeper in the filesystem. To examine the contents of a subfolders, either pass its path as the targetFolder, or temporarily set the defaultFolder.

Files are not included in the list. To get a list of files, use the files function.

Aliases (on OS X systems), symbolic links (on Linux systems) and shortcuts (on Windows systems) are included in the list only if they refer to a folder.

Important

The list returned by the folders contain a ".." entry representing the link to the parent folder. Care must be taken to filter this entry out to prevent infinite loops and security vulnerabilities.

note

The order that folders are listed is platform-dependent. The order may vary between platforms, between filesystems, and even between consecutive calls to the folders function. If you need a sorted list, use the sort command.

Short form

When the folders is called as a function, or without the long or detailed modifiers, it returns only the folder names as a string with one file name per line.

note

On some platforms, folder names are permitted to include the linefeed character. Such a folder name would be split across more than one line of the string returned by the folders function.

Long form

the long folders and the detailed folders are synonyms. When the folders function is called in this form, the return value is a list of folders with detailed file attributes. Several of the attributes are provided only for compatibility with the files function and do not have any meaning for a folder.

Each line in the return value is a comma-separated list of file attributes, as follows:

1. Name. The folder name is URL-encoded. To reliably obtain the name use

   the `detailed-utf8` outputKind and decode using the URLDecode function
   followed by textDecode. For example,
   `textDecode(URLDecode(item 1 of tLine), \"utf8\")`.
2. **Size**, in bytes.  This is always 0.
3. **Resource fork size**, in bytes.  This is always 0.
4. **Creation date**, in seconds.  (OS X and Windows only).
5. **Last modification date**, in seconds.
6. **Last access date**, in seconds.
7. **Last backup date**, in seconds.
8. **User owner**.  (Linux and OS X only).
9. **Group owner**.  (Linux and OS X only).
10. **Permissions**. (Linux and OS X only; see note).
11. **Creator and < fileType|file type:::note[*.  (OS X only).

Any attribute that is not relevant to the current platform is left empty.

The access permissions consist of three octal digits, in the same form used for the umask property.

]

Note:* On Windows, the permissions are always reported as "777".

::: The creator and file type are always "????????".

Parameters

Name	Type	Description
targetFolder	String	The folder path to search.
outputKind	enum

Examples

put folders(specialFolderPath("documents")) into \
      field "Available Folders"
filter lines of field "Available Folders" without ".."
sort lines of field "Available Folders" international

local tDiskContents
put the files & return & the folders into \
      tDiskContents["the defaultFolder"]
filter tDiskContents["the defaultFolder"] without ".."

Related

command: sort

constant: return

function: folders, specialFolderPath, URLDecode, textDecode

glossary: alias, current folder, data fork, folder, function, platform, return, resource fork, shortcut, subfolder, symbolic link

keyword: long

property: defaultFolder, umask

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

web

Platforms

desktop

server

mobile